---
title: Imagens
description: Aprenda como utilizar imagens no Astro.
i18nReady: true
---
import Since from '~/components/Since.astro';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import Badge from '~/components/Badge.astro';
import RecipeLinks from "~/components/RecipeLinks.astro";

Astro fornece diversas formas de utilizar imagens no seu site, sejam elas armazenadas localmente dentro do seu projeto, vinculadas de uma URL externa, ou gerenciadas em um CMS ou CDN!

## Onde armazenar imagens

### `src/` vs `public/`

Nós recomendamos que imagens locais sejam mantidas em `src/` quando possível para que o Astro possa transformar, otimizar e fazer bundle delas. Arquivos no diretório `/public` sempre são servidos ou copiados para a pasta da build como estão, com nenhum processamento.

Suas imagens locais armazenadas em `src/` podem ser usadas por todos os arquivos em seu projeto: `.astro`, `.md`, `.mdx`, `.mdoc`, e outros frameworks de UI. Imagens podem ser armazenadas em qualquer pasta, incluindo ao lado do seu conteúdo.

Armazene suas imagens na pasta `public/` se você quer evitar qualquer processamento ou para ter um link público direto para elas.

### Imagens remotas

Você pode também escolher armazenar suas imagens remotamente, em um sistema de gerenciamento de conteúdo (CMS, do inglês "content management system") ou plataforma de gerenciamento de assets digitais (DAM, do inglês "digital asset management").

Para proteção extra enquanto lida com fontes externas, imagens remotas serão apenas processadas de [fontes de imagem autorizadas](#autorizando-imagens-remotas) especificadas na sua configuração. Contudo, quaisquer imagens remotas podem ser mostradas.

Astro pode buscar dados remotamente usando APIs ou mostrar imagens a partir de seus caminhos de URL completos. Veja nossos [guias de CMS](/pt-br/guides/cms/) para exemplos em como integrar serviços comuns.


## Imagens em arquivos `.astro`

Em arquivos `.astro`, **imagens locais devem ser importadas no arquivo para que sejam utilizadas**. Imagens remotas e de `public/` não precisam ser importadas.

Importe e utilize o componente `<Image />` integrado do Astro para imagens otimizadas utilizando `astro:assets`. Alternativamente, a sintaxe do Astro suporta escrever uma tag `<img>` do HTML diretamente, o que pula o processamento de imagem.

```astro title="src/pages/blog/MinhasImagens.astro"
---
import { Image } from 'astro:assets';
import imagemPassaroLocal from '../../imagens/subpasta/imagemPassaroLocal.png';
---
<Image src={imagemPassaroLocal} alt="Um pássaro sentando em um ninho de ovos."/>
<Image src="/imagens/passaro-na-pasta-public.jpg" alt="Um passáro." width="50" height="50"/>
<Image src="https://exemplo.com/passaro-remoto.jpg" alt="Um passáro." width="50" height="50"/>

<img src={imagemPassaroLocal.src} alt="Um pássaro sentando em um ninho de ovos.">
<img src="/imagens/passaro-na-pasta-public.jpg" alt="Um passáro.">
<img src="https://exemplo.com/passaro-remoto.jpg" alt="Um passáro.">
```

Para importar imagens dinamicamente do diretório `src/`, veja a seguinte receita:

<RecipeLinks slugs={["pt-br/recipes/dynamically-importing-images"]}/>

### `<Image />` (`astro:assets`)

Utilize o componente `<Image />` integrado do Astro para mostrar versões otimizadas de suas imagens locais e [imagens remotas configuradas](#autorizando-imagens-remotas).

Imagens na pasta `public/`, assim como imagens remotas não especificadamente configuradas no seu projeto, também podem ser usadas com o componente Image, mas não serão processadas.

`<Image />` pode transformar as dimensões, tipo de arquivo, e controle da qualidade da sua imagem mostrada local ou autorizada remota. A tag `<img>` resultante inclui os atributos `alt`, `loading` e `decoding` e infere as dimensões da imagem para evitar **Cumulative Layout Shift (CLS)**.

:::tip[O que é Cumulative Layout Shift?]
[Cumulative Layout Shift (CLS) ou Mudança Cumulativa de Layout](https://web.dev/cls/), é uma métrica do Core Web Vitals para mensurar o quanto o conteúdo da sua página se moveu durante o carregamento. O componente `<Image />` otimizada para CLS ao automaticamente definir o `width` e `height` corretos para suas imagens locais.
:::

```astro title="src/components/MeuComponente.astro"
---
// importe o componente Image e a imagem
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png"; // Imagem é 1600x900
---

<!-- `alt` é obrigatório no componente Image -->
<Image src={minhaImagem} alt="Uma descrição de minha imagem." />
```

```html
<!-- Resultado -->
<!-- Imagem é otimizada, atributos adequados são aplicados -->
<img
  src="/_astro/minha_imagem.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Uma descrição de minha imagem."
/>
```

#### Propriedades

##### src (obrigatório)

O formato do valor `src` de sua imagem depende de onde o seu arquivo de imagem está localizado:

- **Imagens locais em `src/`** - você deve **também importar a imagem** utilizando um caminho de arquivo relativo ou configurar e utilizar um [atalho de importação](/pt-br/guides/aliases/). Então, utilize o nome de importação como o valor de `src`:

  ```astro title="src/pages/index.astro" "minhaImagemImportada" "{minhaImagemImportada}"
  ---
  import { Image } from 'astro:assets';
  import minhaImagemImportada from `../assets/minha-imagem-local.png`
  ---
  <Image src={minhaImagemImportada} alt="texto descritivo" />
  ```

- **Imagens na pasta `public/`** -  utilize o **caminho de arquivo da imagem relativo a pasta public**:

  ```astro title="src/pages/index.astro" '"/imagens/minha-imagem-publica.png"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="/imagens/minha-imagem-publica.png"
    alt="texto descritivo"
    width="200"
    height="150"
  />
  ```

- **Imagens remotas** - utilize a **URL completa** da imagem como o valor da propriedade:

  ```astro title="src/pages/index.astro" '"https://exemplo.com/imagem-remota.jpg"'
  ---
  import { Image } from 'astro:assets';
  ---
  <Image
    src="https://exemplo.com/imagem-remota.jpg"
    alt="texto descritivo"
    width="200"
    height="150" />
  ```

##### alt (obrigatório)

Utilize o atributo `alt` obrigatório para fornecer uma string de [texto alternativo descritivo](https://www.w3.org/WAI/tutorials/images/) para imagens.

Se uma imagem é meramente decorativa (ou seja, não contribui para o entendimento da página), defina `alt=""` para que leitores de tela e outras tecnologias assistivas saibam ignorar a imagem.

##### width e height (obrigatório para imagens remotas e de `public/`)

Essas propriedades definem as dimensões a se utilizar para a imagem.

Ao utilizar imagens em sua proporção de tela original, o `width` e `height` são opcionais. Essas dimensões podem ser inferidos automaticamente a partir de arquivos de imagem localizados em `src/` e a partir de imagens remotas com [`inferSize` definido como `true`](#infersize).

Porém, ambas essas propriedades são obrigatórias para imagens armazenadas em sua pasta `public/` já que o Astro é incapaz de analisar esses arquivos.

##### densities

<p><Since v="3.3.0" /></p>

Uma lista de densidades de pixels para gerar a imagem

Se atribuído, o valor é usado para gerar o atributo `srcset`na tag `<img>`. Você não deve prover um valor para `widths` quando tiver usando esse atributo.

As densidades que são iguais a larguras maiores do que a imagem original serão ignoradas para evitar o aumento da escala da imagem.

```astro title="src/components/MeuComponente.astro"
---
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png";
---
<Image src={minhaImagem} width={minhaImagem.width / 2} densities={[1.5, 2]} alt="Uma descrição para imagem." />
```

```html
<img
  src="/_astro/minha_imagem.hash.webp"
  srcset="
    /_astro/minha_imagem.hash.webp 1.5x
    /_astro/minha_imagem.hash.webp 2x
  "
  alt="Uma descrição para imagem."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
```

##### widths

<p><Since v="3.3.0" /></p>

Uma lista de larguras a serem geradas para a imagem.

Se fornecido, esse valor será usado para gerar um atributo `srcset` na tag `<img>` Uma [propriedade sizes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) também deve ser fornecida.

Não forneça um valor para `densities` ao usar este valor. Apenas um destes dois valores pode ser usado para gerar um srcset.

Larguras que forem maiores do que a imagem original serão ignoradas para evitar o redimensionamento da imagem.

```astro
---
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png"; // Image is 1600x900
---
<Image
  src={minhaImagem}
  widths={[240, 540, 720, minhaImagem.width]}
  sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${minhaImagem.width}px`}
  alt="Uma descrição para minha imagem."
/>
```

```html
<img
  src="/_astro/minha_imagem.hash.webp"
  srcset="
    /_astro/minha_imagem.hash.webp 240w,
    /_astro/minha_imagem.hash.webp 540w,
    /_astro/minha_imagem.hash.webp 720w,
		/_astro/minha_imagem.hash.webp 1600w
  "
  sizes="
    (max-width: 360px) 240px,
    (max-width: 720px) 540px,
    (max-width: 1600px) 720px,
    1600px
  "
  alt="Uma descrição para minha imagem."
  width="1600"
  height="900"
  loading="lazy"
  decoding="async"
/>
```
 
##### format

Você pode opcionalmente definir um [tipo de arquivo de imagem](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types#common_image_file_types) final para ser utilizado.

Por padrão, o componente `<Image />` irá produzir um arquivo `.webp`.

##### quality

`quality` é uma propriedade que pode tanto ser:
- uma predefinição (`low`, `mid`, `high`, `max`) que é automaticamente normalizada entre formatos.
- um número de `0` a `100` (interpretado diferentemente entre formatos).

##### inferSize

<p><Since v="4.4.0" /></p>

Te permite definir os valores oridinais de `width` e `height` para imagens remotas automaticamente.

Por padrão, essa propriedade é definida como `false` e você deve especificar ambas as dimensões para sua imagem remota.

Adicione `inferSize` ao componente `<Image />` (ou `inferSize: true` em `getImage()`) para inferrir esses valores da imagem remota quando baixada. Isso é útil quando você não sabe as dimensões da imagem remota, ou quando elas podem mudar.

```astro mark="inferSize"
---
import { Image } from 'astro:assets';
---
<Image src="https://example.com/cat.png" inferSize alt="Um gato dormindo no sol."/>
```

`inferSize` pode baixar informações de uma [imagem remota de um domínio que não foi autorizado](#autorizando-imagens-remotas), no entanto, a imagem em si não sera processada.

##### Propriedades adicionais

Em adição as propriedades acima, o componente `<Image />` aceita todas as propriedades aceitas pela tag `<img>` do HTML.

Por exemplo, você pode fornecer uma `class` para o elemento `<img>` final.

```astro title="src/pages/index.astro"
---
import { Image } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png";
---

<!-- `alt` é obrigatório no componente Image -->
<Image src={minhaImagem} alt="" class="minha-classe" />
```

```html
<!-- Resultado -->
<img
  src="/_astro/minha_imagem.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="minha-classe"
  alt=""
/>
```

#### Definindo Valores Padrões

Atualmente, não há uma forma de especificar valores padrões para todos os componentes `<Image />`. Atributos obrigatórios devem ser definidos em cada componente individual.

Como uma alternativa, você pode envolver esses componentes em outro componente Astro para reutilização. Por exemplo, você poderia criar um componente para suas imagens de postagens do blog:

```astro title="src/components/ImagemPostBlog.astro"
---
import { Image } from 'astro:assets';

const {src, ...attrs} = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img :global(img), svg {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```


### `<Picture />`

<p><Since v="3.3.0" /></p>

Utilize o componente `<Picture />` integrado do Astro para exibir uma imagem responsiva com vários formatos e/ou tamanhos.

```astro title="src/pages/index.astro"
---
import { Picture } from 'astro:assets';
import minhaImagem from "../assets/minha_imagem.png"; // Image is 1600x900
---

<!-- `alt` é obrigatório no componente Picture -->
<Picture src={minhaImagem} formats={['avif', 'webp']} alt="Uma descrição para a minha imagem." />
```

```html
<!-- Output -->
<picture>
  <source srcset="/_astro/minha_imagem.hash.avif" type="image/avif" />
  <source srcset="/_astro/minha_imagem.hash.webp" type="image/webp" />
  <img
    src="/_astro/minha_imagem.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Uma descrição para a minha imagem."
  />
</picture>
```

#### Propriedades

`<Picture />` aceita todas as propriedades do componente `<Image />`, juntamente com:

##### `formats`

Um array de formatos de imagem a serem usados para as tags `<source>`. As entradas serão adicionadas como elementos `<source>` na ordem em que estão listadas, e essa ordem determina qual formato é exibido. Para obter o melhor desempenho, liste o formato mais moderno primeiro (por exemplo, `webp` ou `avif`). Por padrão, isso é configurado como `['webp']`.

##### `fallbackFormat`

Formato a ser usado como um valor de fallback para a tag `<img>`.

Por padrão, é configurado como `.png` para imagens estáticas (ou `.jpg` se a imagem for um JPG), `.gif` para imagens animadas e `.svg` para arquivos SVG.

##### `pictureAttributes`

Um objeto de atributos a serem adicionados à tag `<picture>`.

Use essa propriedade para aplicar atributos ao elemento externo `<picture>`. Atributos aplicados diretamente ao componente `<Picture />` serão aplicados internamente ao elemento `<img>`, exceto aqueles usados para a transformação da imagem.

```astro title="src/components/MeuComponente.astro"
---
import { Picture } from "astro:assets";
import minhaImagem from "../minha_imagem.png"; // Image is 1600x900
---

<Picture src={minhaImagem} alt="Uma descrição para a minha imagem." pictureAttributes={{style: "background-color: red;"}} />
```

```html
<picture style="background-color: red;">
  <source srcset="/_astro/minha_imagem.hash.webp" type="image/webp" />
  <img
    src="/_astro/minha_imagem.hash.png"
    alt="Uma descrição para a minha imagem."
    width="1600"
    height="900"
    loading="lazy"
    decoding="async"
  />
</picture>
```

### `<img>`

A [sintaxe de templates do Astro](/pt-br/basics/astro-syntax/) também suporta escrever uma tag `<img>` diretamente, com controle total sobre seu resultado final. Essas imagens não serão processadas e otimizadas.

Ela aceita todas as propriedades da tag `<img>` do HTML, e a única propriedade obrigatória é `src`.

#### Imagens locais em `src/`

Imagens locais devem ser **importadas de seu caminho relativo** a partir do arquivo `.astro` existente, ou configure e utilize um [atalho de importação](/pt-br/guides/aliases/). Então, você pode acessar o `src` da imagem e outras propriedades para utilizar na tag `<img>`.

Por exemplo, utilize as propriedades `height` e `width` da imagem para evitar CLS e melhorar os Core Web Vitals.

```astro title="src/pages/posts/post-1.astro" "meuCachorro.width" "meuCachorro.height"
---
// importe imagens locais
import meuCachorro from `../../imagens/pets/cachorro-local.jpg`
---
// acesse propriedades da imagem
<img src={meuCachorro.src} width={meuCachorro.width} height={meuCachorro.height} alt="Um cachorro latindo." />
```

Assets de imagem importadas correspondem a seguinte assinatura:

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

#### Imagens em `public/`
Para imagens localizadas em `public/` utilize o **caminho do arquivo relativo a pasta public** da imagem como o valor `src`:

```astro '"/imagens/gato-em-public.jpg"'
<img src="/imagens/gato-em-public.jpg" alt="Um gato dormindo.">
```

#### Imagens remotas

Para imagens remotas, utilize a **URL completa** da imagem como o valor de `src`:

```astro '"https://exemplo.com/gato-remoto.jpg"'
<img src="https://exemplo.com/gato-remoto.jpg" alt="Um gato dormindo.">
```

### Escolhendo `<Image />` vs `<img>`

O componente `<Image />` otimiza sua imagem e infere a largura e altura (de imagens locais) com base na proporção de tela original para evitar CLS.

Utilize o elemento `<img>` do HTML quando você não pode utilizar o componente `<Image />`, por exemplo:
  - para formatos de imagem não suportados
  - quando você não quer que sua imagem seja otimizada pelo Astro
  - para acessar e modificar o atributo `src` dinamicamente no lado do cliente


### Autorizando imagens remotas

Você pode configurar listas de domínios e padrões de URL fonte de imagens autorizadas para otimização de imagem utilizando [`image.domains`](/pt-br/reference/configuration-reference/#imagedomains) e [`image.remotePatterns`](/pt-br/reference/configuration-reference/#imageremotepatterns). Essa configuração é uma camada adicional de segurança para proteger seu site ao mostrar imagens de uma fonte externa.

Imagens remotas de outras fontes não serão otimizadas, mas utilizando o componente `<Image />` para essas imagens irá prevenir Cumulative Layout Shift (CLS).

Por exemplo, a seguinte configuração irá apenas permitir imagens remotas de `astro.build` a serem otimizadas:

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});
```

A seguinte configuração irá apenas permitir imagens remotas de hospedagens HTTPS:

```ts
// astro.config.mjs
export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});
```

## Utilizando Imagens de CMS ou CDN

CDNs de imagem funcionam com todas as opções de imagem do Astro. Utilize a URL completa de uma imagem como o atributo `src` no componente `<Image />`, em uma tag `<img>`, ou na notação do Markdown. Para otimização de imagem com imagens remotas, também [configure seus domínios e padrões de URL autorizados](#autorizando-imagens-remotas).

Alternativamente, se o CDN fornece um SDK para Node.js, você pode utilizá-lo em seu projeto. Por exemplo, o [SDK da Cloudinary](https://cloudinary.com/documentation/node_integration) pode gerar uma tag `<img>` com o `src` apropriado para você.

## Imagens em arquivos Markdown

Utilize a sintaxe padrão do Markdown `![alt](src)` em seus arquivos `.md`. Essa sintaxe funciona com a [API de Serviço de Imagem](/pt-br/reference/image-service-reference/) do Astro para otimizar suas imagens locais e imagens remotas autorizadas.

```md
<!-- src/pages/post-1.md -->

# Minha Página Markdown

<!-- Imagem local armazenada em src/assets/ -->
<!-- Utilize um caminho de arquivo relativo ou atalho de importação -->
![Uma noite com um céu estrelado.](../assets/estrelas.png)

<!-- Imagem armazenada em public/imagens/ -->
<!-- Utilize o caminho de arquivo relativo ao public/ -->
![Uma noite com um céu estrelado.](/imagens/estrelas.png)

<!-- Imagem remota em outro servidor -->
<!-- Utilize a URL completa da imagem -->
![Astro](https://exemplo.com/imagens/imagem-remota.png)
```

A tag `<img>` não é suportada para imagens locais, e o componente `<Image />` está indisponível em arquivos `.md`.

Se você precisa de mais controle sobre seus atributos da imagem, nós recomendamos utilizar o formato de arquivo `.mdx`, que te permite incluir o componente `<Image />` do Astro ou uma tag `<img />` JSX em adição a sintaxe do Markdown. Utilize a [integração MDX](/pt-br/guides/integrations-guide/mdx/) para adicionar suporte para MDX ao Astro.

## Imagens em arquivos MDX

Você pode utilizar o componente `<Image />` do Astro e tags `<img />` JSX em seus arquivos `.mdx` importando ambos o componente e sua imagem. Utilize-os assim como eles são [utilizados em arquivos `.astro`](#imagens-em-arquivos-astro).

Adicionalmente, há suporte para [sintaxe padrão do Markdown `![alt](src)`](#imagens-em-arquivos-markdown) com nenhuma importação necessária.

```mdx title="src/pages/post-1.mdx"
---
titulo: Título da Minha Página
---
import { Image } from 'astro:assets';
import foguete from '../assets/foguete.png';

# Minha Página MDX

// Imagem local armazenada em src/assets/
<Image src={foguete} alt="Um foguete no espaço."/>
<img src={foguete.src} alt="Um foguete no espaço." />
![Um foguete no espaço](../assets/foguete.png)

// Imagens armazenada em public/imagens/
<Image src="/imagens/estrelas.png" alt="Uma noite com um céu estrelado." />
<img src="/imagens/estrelas.png" alt="Uma noite com um céu estrelado." />
![Uma noite com um céu estrelado.](/imagens/estrelas.png)

// Imagem remota em outro servidor
<Image src="https://exemplo.com/imagens/imagem-remota.png" />
<img src="https://exemplo.com/imagens/imagem-remota.png" />
![Astro](https://exemplo.com/imagens/imagem-remota.png)

```

## Imagens em coleções de conteúdo

Imagens em coleções de conteúdo serão processadas da mesma forma que em arquivos [Markdown](#imagens-em-arquivos-markdown) e [MDX](#imagens-em-arquivos-mdx) dependendo do tipo do arquivo que estiver usando.

Adicionalmente, você pode declarar uma imagem associada para uma entrada de coleções de conteúdo, como a imagem de capa de uma postagem de blog, em seu frontmatter utilizando o caminho relativo a pasta atual:

```md title="src/content/blog/minha-postagem.md" {3}
---
title: "Minha primeira postagem do blog"
capa: "./capaprimeirapostagem.jpeg" # será resolvido como "src/content/blog/capaprimeirapostagem.jpeg"
altCapa: "Uma fotografia de um pôr do sol atrás de uma cadeia de montanhas."
---

Essa é uma postagem no blog
```

O utilitário `image` para esquemas de coleções de conteúdo te permite validar os metadados da imagem utilizando Zod.

```ts title="src/content/config.ts"
import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		titulo: z.string(),
		capa: image().refine((img) => img.width >= 1080, {
			mensagem: "Imagem de capa deve ter pelo menos 1080 pixels de largura!",
		}),
		altCapa: z.string(),
	}),
});

export const collections = {
	blog: blogCollection,
};
```

A imagem será importada e transformada em metadados, te permitindo passá-la como o `src` para `<Image/>`, `<img>`, ou `getImage()`.

O exemplo abaixo mostra a página de índice de um blog que renderiza a foto de capa e o título de cada postagem do blog do esquema acima:

```astro title="src/pages/blog.astro" {10}
---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const todasPostagensBlog = await getCollection("blog");
---

{
	todasPostagensBlog.map((post) => (
		<div>
			<Image src={post.data.capa} alt={post.data.capaAlt} />
			<h2>
				<a href={"/blog/" + post.slug}>{post.data.titulo}</a>
			</h2>
		</div>
	))
}
```

## Imagens em componentes de frameworks de UI

Ao adicionar imagens em um componente de framework de UI, utilize a sintaxe de imagem própria do framework para renderizar uma imagem (e.x. `<img />` em JSX, `<img>` em Svelte).

Imagens locais devem **primeiro ser importadas** para acessar suas [propriedades de imagem](#imagens-locais-em-src) como `src`.

```jsx title="src/components/ImagemReact.jsx"
import estrelas from "../assets/estrelas.png"

export default function ImagemReact() {
  return (
    <img src={estrelas.src} alt="Uma noite com um céu estrelado." />
  )
}
```

```svelte title="src/components/ImagemSvelte.svelte"
<script>
  import estrelas from '../assets/estrelas.png'
</script>

<img src={estrelas.src} alt="Uma noite com um céu estrelado." />

```

#### Passando o componente Image

O componente `<Image />`, assim como qualquer outro componente Astro, **não está disponível para componentes de frameworks de UI**.

Porém, você pode passar o conteúdo estático gerado por `<Image />` para um componente de framework dentro de um arquivo `.astro` como um filho ou utilizando um [`<slot/>` nomeado](/pt-br/guides/framework-components/#posso-utilizar-componentes-astro-dentro-de-meus-componentes-de-frameworks):


```astro title="EnvolvedorImagem.astro"
---
import ComponenteReact from './ComponenteReact.jsx';
import { Image } from "astro:assets"
import estrelas from "~/estrelas/docline.png";
---

<ComponenteReact>
  <Image src={estrelas} alt="Uma noite com um céu estrelado." />
</ComponenteReact>
```

## Gerando imagens com `getImage()`

:::caution
`getImage()` depende em APIs únicas do servidor e quebra a build quando é utilizado no cliente.
:::

A função `getImage()` foi planejada para gerar imagens destinadas a serem em outro lugar do que diretamente no HTML, por exemplo em uma [Rota de API](/pt-br/guides/endpoints/#endpoints-do-servidor-rotas-de-api). Ela te permite criar seu próprio componente `<Image />` customizado.

<RecipeLinks slugs={["pt-br/recipes/build-custom-img-component" ]}/>

`getImage()` recebe um objeto de opções com as [mesmas propriedades que o componente Image](#propriedades) (exceto `alt`).

```astro
---
import { getImage } from "astro:assets";
import meuPlanoFundo from "../planoFundo.png"

const planoFundoOtimizado = await getImage({src: meuPlanoFundo, format: 'webp'})
---

<div style={`background-image: url(${planoFundoOtimizado.src});`}></div>
```

Retorna um objeto com as seguintes propriedades:

```js
{
  rawOptions: {...} // Parâmetros originais passados
  options: {...}, // Parametros validados passados
  src: "https//..." // Caminho para a imagem gerada
  srcSet: {
    values: [...], // Valores gerados para srcset, cada entrada tem uma url e uma descrição de tamanho
    attribute: "", // Atributo srcset gerado a partir dos valores
  }
  attributes: {...} // Atributos HTML adicionais necessários para renderizar a imagem (width, height, style, etc..)
}
```

## Texto Alternativo

Nem todos os usuários podem ver imagens da mesma forma, então acessibilidade é uma preocupação especialmente importante ao utilizar imagens. Utilize o atributo `alt` para fornecer [texto alternativo descritivo](https://www.w3.org/WAI/tutorials/images/) para imagens.

Esse atributo é necessário para ambos os componentes `<Image />` e `<Picture />`. Se nenhum texto alternativo for fornecido, uma mensagem de erro será exibida te lembrando de incluir o atributo `alt`.

Se a imagem for meramente decorativa (ou seja, não contribui para o entendimento da página), defina `alt=""` para que leitores de tela saibam ignorar a imagem.

## Serviço de imagem padrão

[Sharp](https://github.com/lovell/sharp) é o serviço de imagem padrão utilizado em `astro:assets`. Você pode configurar o serviço de imagem utilizando a opção [`image.service`](/pt-br/reference/configuration-reference/#imageservice).

:::note
Ao usar um [gerenciador de pacotes rigoroso](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) como o `pnpm`, talvez seja necessário instalar o Sharp manualmente o seu projeto, mesmo que seja uma dependência do Astro:

```bash
pnpm add sharp
```
:::

### Configure o Squoosh

Se você preferir utilizar [Squoosh](https://github.com/GoogleChromeLabs/squoosh) para transformar suas imagens, atualize sua configuração com o seguinte:

```js title="astro.config.mjs" ins={4-6}
import { defineConfig, squooshImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: squooshImageService(),
  },
});
```

### Configure o serviço de passagem não-operacional

Se o seu [adaptador para modo `server` ou `hybrid`](https://astro.build/integrations/?search=&categories%5B%5D=adapters) não suportar os serviços de otimização Squoosh e Shart integrados do Astro (e.g. Deno, Cloudflare), você pode configurar um serviço de imagem não-operacional para permitir que utilize os componentes `<Image />` e `<Picture />`. Note que o Astro não executa nenhuma transformação e processamento de imagens nesses ambientes. No entanto, você ainda pode os outros benefícios de utilizar o `astro:assets`, incluindo não ter Cumulative Layout Shift (CLS), a exigência do atributo `alt`, e a experiência de autoria consistente.

Configure o `passthroughImageService` para evitar ambos os processamentos de imagem Squoosh e Sharp:

```js title="astro.config.mjs" ins={4-6} "passthroughImageService"
import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});
```

## Integrações da Comunidade

Há diversas [integrações de imagem da comunidade](https://astro.build/integrations?search=images) por terceiros para otimizar e trabalhar com imagens em seu projeto Astro.

## Atualize para v3.0 da v2.x

`astro:assets` não está mais atrás de uma flag experimental no Astro v3.0.

`<Image />` agora é um componente integrado e a integração `@astrojs/image` anterior foi removida.

Essa e outras mudanças em como utilizar imagens no Astro pode causar algumas mudanças radicais ao atualizar seu projeto Astro de uma versão anterior.

Por favor siga as instruções abaixo apropriadamente para atualizar um projeto Astro v2.x para v3.0.

### Atualize de `experimental.assets`

Se você anteriormente habilitou a flag experimental para `astro:assets`, você vai precisar atualizar seu projeto para Astro v3.0 que agora inclui funcionalidades de assets por padrão.

#### Remova a flag `experimental.assets`

Remova a flag experimental:

```js title="astro.config.mjs" del={4-6}
import { defineConfig } from 'astro/config';

export default defineConfig({
  experimental: {
   assets: true
  }
});
```

Se necessário, também atualize seu arquivo `src/env.d.ts` para substituir a referência `astro/client-image` com `astro/client`:

```ts title="src/env.d.ts" del={1} ins={2}
/// <reference types="astro/client-image" />
/// <reference types="astro/client" />
```

#### Remova o atalho de importação `~/assets`

Esse atalho de importação não é mais incluso por padrão com `astro:assets`. Se você esteve utilizando esse atalho com assets experimentais, você deve convertê-los para camianhos de arquivo relativos, ou [criar seu próprio atalho de importação](/pt-br/guides/aliases/).

```astro title="src/pages/posts/post-1.astro" del={2} ins={3}
---
import foguete from '~/assets/foguete.png'
import foguete from '../../assets/foguete.png';
---
```

#### Adicione suporte simples de assets para Cloudflare, Deno, Vercel Edge e Netlify Edge

Astro v3.0 permite `astro:assets` funcionar sem erros em Cloudflare, Deno, Vercel Edge e Netlify Edge, que não suporta a otimização integrada do Astro, Squoosh e Sharp. Note que Astro não realiza nenhuma transformação e processamento de imagem nesses ambientes. Porém, você ainda pode aproveitar os outros benefícios de se utilizar `astro:assets`, incluindo nenhum Cumulative Layout Shift (CLS), a aplicação do atributo `alt`, e a experiência de autoria consistente.

Se você anteriormente evitou utilizar `astro:assets` por conta dessas limitações, agora você pode utilizá-lo sem problemas. Você pode configurar o serviço de imagem no-op para explicitamente optar por esse compartamento:

```js title="astro.config.mjs" ins={4-8}
import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    service: {
      entrypoint: 'astro/assets/services/noop'
    }
  }
});
```

### Decida onde armazenar suas imagens

Veja o guia de Imagens para te ajudar a decidir [onde armazenar suas imagens](#onde-armazenar-imagens). Você pode desejar se aproveitar de novas opções para armazenar suas imagens com a flexibilidade adicional que `astro:assets` traz. Por exemplo, imagens relativas a partir do `src/` do seu projeto podem ser referenciadas em Markdown, MDX e Markdoc utilizando a sintaxe padrão do Markdown `![alt](src)`.

### Atualize tags `<img>` existentes

Anteriormente, importar uma imagem iria retornar uma simples `string` com o caminho da imagem. Agora, assets de imagem importadas correspodem a seguinte assinatura:

```ts
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

Você deve atualizar o atributo `src` de quaisquer tags `<img>` existentes (incluindo quaisquer [imagens em componentes de framework de UI](#imagens-em-componentes-de-frameworks-de-ui)) e você também pode atualizar outros atributos que agora estão disponíveis para você da imagem importada.

```astro title="src/components/MeuComponente.astro" ".src" ".width" ".height" del={4} ins={6}
---
import foguete from '../imagens/foguete.svg';
---
<img src={foguete} width="250" height="250" alt="Um foguete no espaço." />

<img src={foguete.src} width={foguete.width} height={foguete.height} alt="Um foguete no espaço." />
```

### Atualize seus arquivos Markdown, MDX e Markdoc

Imagens relativas da `src/` do seu projeto agora podem ser referenciadas em Markdown, MDX e Markdoc utilizando a sintaxe padrão do Markdown `![alt](src)`.

Isso te permite mover suas imagens do diretório `public/` para o `src/` do seu projeto onde agora elas serão processadas e otimizadas. Suas imagens existentes em `public/` e imagens remotas ainda são válidas mas não são otimizadas pelo processo de build do Astro.

```md title="src/pages/posts/post-1.md" "/_astro" ".hash" "../../assets/"
# Minha Página Markdown

<!-- Imagens locais agora são possíveis! -->
![Uma noite com um céu estrelado.](../../imagens/estrelas.png)

<!-- Mantenha suas imagens próximas do seu conteúdo! -->
![Uma noite com um céu estrelado.](./estrelas.png)
```

Se você requer mais controle sobre seus atributos de imagem, nós recomendamos utilizar o formato de arquivo `.mdx`, que te permite incluir o componente `<Image />` do Astro ou uma tag `<img />` JSX em adição a sintaxe do Markdown. Utilize a [integração MDX](/pt-br/guides/integrations-guide/mdx/) para adicionar suporte de MDX para Astro.

### Remova `@astrojs/image`


Se você estava utilizando a integração de imagem em Astro v2.x, complete as seguintes etapas:

1. Remova a integração `@astrojs/image`.

    Você deve [remover a integração](/pt-br/guides/integrations-guide/#removendo-uma-integração) a desinstalando e então a removendo do seu arquivo `astro.config.mjs`.

    ```js del={3,7}
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import image from '@astrojs/image';

    export default defineConfig({
      integrations: [
        image(),
      ]
    })
    ```
2. Atualize tipos (se necessário).

		Se você tinha tipos especiais configurados para `@astrojs/image` em `src/env.d.ts`, pode ser necessário alterá-los de volta para os tipos padrão do Astro se a atualização para a versão 3 não concluiu esta etapa automaticamente para você.
		

		```ts title="src/env.d.ts" del={1} ins={2}
		 /// <reference types="@astrojs/image/client" />
		 /// <reference types="astro/client" />
		```

    Uma atualização similar se necessária deve ser aplicada no `tsconfig.json`:

		```json title="tsconfig.json" del={3} ins={4}
		{
			"compilerOptions": {
			  "types": ["@astrojs/image/client"]
			  "types": ["astro/client"]
			}
		}
		```

3. Migre quaisquer componentes `<Image />`.

    Modifique todas as declarações `import` de `@astrojs/image/components` para `astro:assets` para utilizar o novo componente `<Image />` integrado.

    Remova quaisquer atributos do componente que não são [propriedades de asset de imagem atualmente suportadas](#propriedades).

    Por exemplo, `aspectRatio` não é mais suportado, já que agora é automaticamente inferido dos atributos `width` e `height`.

      ```astro title="src/components/MeuComponente.astro" del= {2,11} ins={3}
      ---
      import { Image } from '@astrojs/image/components';
      import { Image } from 'astro:assets'
      import imagemLocal from "../assets/logo.png";
      const altLocal = "A logo do Astro";
      ---

      <Image
        src={imagemLocal}
        width={300}
        aspectRatio="16:9"
        alt={altLocal}
      />
      ```

4. Escolha o serviço de imagem padrão.

    [Sharp](https://github.com/lovell/sharp) agora é o serviço de imagem padrão usado para `astro:assets`. Se você quiser utilizar Sharp, nenhuma configuração é necessária.

    Se você preferir utilizar [Squoosh](https://github.com/GoogleChromeLabs/squoosh) para transformar suas imagens, atualize sua configuração com a opção `image.service` a seguir:

    ```js title="astro.config.mjs" ins={4-6}
    import { defineConfig, squooshImageService } from 'astro/config';

    export default defineConfig({
      image: {
        service: squooshImageService(),
      },
    });
    ```

### Atualize Esquemas de Coleções de Conteúdo

Agora você pode declarar uma imagem associada a uma entrada de coleções de conteúdo, como a imagem de capa de uma postagem de blog, em seu frontmatter utilizando seu caminho relativo a pasta atual.

O novo utilitário `image` para coleções de conteúdo te permite validar os metadados da imagem utilizando Zod. Aprenda mais sobre [como utilizar imagens em coleções de conteúdo](/pt-br/guides/images/#imagens-em-coleções-de-conteúdo)

### Navegando Importações de Imagem no Astro v3.0

No Astro v3.0, se você precisar preservar o antigo comportamento de importação para imagens e exigir uma representação de string do URL da imagem, adicione `?url` ao final do caminho da sua imagem ao importá-la. Por exemplo: 

```astro title="src/pages/blog/MinhasImagens.astro"
---
import Sprite from '../assets/logo.svg?url';
---
  <svg>
    <use xlink:href={Sprite + '#carrinho'} />
  </svg>
```

Essa abordagem garante que você obtenha a string de URL. Tenha em mente que, durante o desenvolvimento, o Astro usa um caminho `src/`, mas, ao fazer build, ele gera caminhos com hash como `/_astro/gato.a6737dd3.png`. 

Se você preferir trabalhar diretamente com o próprio objeto de imagem, você pode acessar a propriedade `.src`. Essa abordagem é melhor para tarefas como gerenciar as dimensões da imagem para métricas Core Web Vitals e prevenir o CLS. 

Se você estiver em transição para o novo comportamento de importação, combinar os métodos `?url` e `.src` pode ser o método certo para o manuseio de imagens ininterrupto.
